TRANSFERRING RTF FILES BETWEEN THE SERIES 3 AND THE APPLE MACINTOSH
1 Introduction
There are a number of limitations and difficulties encountered when transferring documents in Rich Text Format (RTF) between Word on a Psion Series 3 and Microsoft Word on an Apple Macintosh. The latest RTF drivers and the use of Style Maps goes some way to improving matters, but the Style Maps still have to be manually prepared to produce satisfactory results.
I have produced a pair of programs which overcome most of these problems, and in particular automate the production and use of Style Maps with sensible mappings.
2 The Problems
2.1 Character Sets
The Macintosh uses a different character set to the Series 3. Characters with codes less than 128 (decimal), i.e. the ASCII set, are identical. Other characters are different. Sometimes a character in one set has an equivalent in the other set, but with a different code. In other cases there is no equivalent. The characters in question include all the accented characters, special punctuation characters, as well as that extremely useful (for us Brits!) pound sign.
In theory the RTF format should cater for this. Non ASCII characters are represented in the form "\'hh", where hh is the two digit hexadecimal value of its code in the originating character set. The header of the RTF file includes an indication of the origin of the file; e.g. "\pca" for the Series 3, "\mac" for the Macintosh. This should enable the destination program to convert the non ASCII characters to their local equivalent.
In practice the version of Word I use on my Macintosh (v4) only manages to convert correctly characters with codes between 128 and 137. Other characters are converted to a default value. This may be a reflection of the fact there is no 'standard' PC character set.
The Series 3 appears to convert all Macintosh characters correctly. At least Psion got that bit right!
2.2 Font Mapping
Font definitions in RTF have two parts: a family and a name. E.g. froman Times, where froman is the family and Times the name, or fswiss Helvetica, where fswiss is the family and Helvetica the name.
When reading font definitions Word on the Series 3 looks for an exact match between the family/name combination and the valid combinations defined in the currently set printer driver. If there is no match then it assigns a known font with a matching family.
Unfortunately the family/name combinations generated by my Mac (configured for printing to an Apple Laserwriter) do not correspond to those defined in the Series 3 Apple Laserwriter driver. For example the Mac outputs fnil Palatino, while the Series 3 expects froman Palatino and assigns Courier instead!
The Mac appears to match on name rather than family, e.g. incoming froman Palatino is mapped onto Palatino, far more logical and useful. Psion 1, Apple 1!
2.3 Style Names
When reading RTF style definitions Word on the Series 3 attempts to derive a short code for the style from the first two characters of the style's name. However if this doesn't form a valid and unique code then a default (meaningless) code is assigned. At least the real name is now preserved in all cases, as the "full" name.
When generating an output RTF style sheet then only the short code is output, except for certain 'standard' styles, e.g. Body Text.
The result is that if you export a document to the Series 3 to work on, and then copy it back to the Mac, all the original style names will be 'lost'. The document's style sheet will be full of meaningless names such as ZA, etc.
3 The Solutions
The solution I have adopted for the problem with non ASCII characters is as follows:
I convert the hexadecimal representation of the character to the actual character itself, in the Series 3 character set. I then rely on the conversions carried out by the MCLINK program to convert it to the corresponding character in the Mac character set. I also change the RTF header to make it appear that the RTF file originated on the Mac, to suppress any further conversion by Mac Word.
The problem with fonts is now readily solved by setting up a suitable style and font mapping file. See the documentation distributed with the latest RTF drivers (available from 3-Lib in RTF220.ZIP).
The difficulties with style names are also overcome using a mapping file, which is generated automatically for each RTF file to be imported to the Series 3. A more intelligent algorithm is used to ensure a meaningful short code is generated for virtually any style name. This tries the following combinations in order, until a previously unused code is formed.
ú If the style name contains more than one word (space separated), the first character of the first and second words;
ú The first and second characters of the style name;
ú Then the first and third characters, etc.;
ú Finally, if all else fails, the combinations QA, QB, etc.
In all cases lower case letters are converted to upper case, and the digits 1 to 9 to letters A to I.
The outline level is set as follows:
ú If the style name is of the form HEAD... n, n = 1 .. 9 (ignoring case): n;
ú If the style name is of the form HEAD...: 1;
ú Otherwise: 9.
This mapping file is saved for use when the document is transferred back to the Mac. This then ensures the style definitions are output to the RTF file with their correct full names.
4 The Programs
4.1 Installation and Preparation
There are two versions of each program, for the Series 3 and Series 3A. The only difference is the Series 3A has a fancier progress bar using the grey plane.
For the Series 3 copy RTFMACS3.OPA and MACRTFS3.OPA to \APP on any of the Series 3's drives. For the Series 3A similarly copy RTFMAC3A.OPA and MACRTF3A.OPA. Then install these applications as normal, using Psion-I on the System screen. You may find it helpful to assign a button to RTFMAC.
You must also set up a default mapping file: RTFMAP.DEF, in \WDR on the internal drive M:. This should contain the mapping between the font names generated on the Mac and corresponding font ids used by the Series 3.
I have included the file I use, which I have configured for the fonts I commonly use on an Apple Laserwriter. If you wish to set up your own font mappings then you need to find out the family/name combinations which your Mac generates. Do this by saving a document in RTF format from Word on the Mac, and then examining the resultant file. The font definitions are in a block beginning "{\fontbl...", which contains entries of the form "{\fid family name;}". The corresponding ids used by the Series 3 can be obtained from the table in the documentation with the latest RTF drivers.
You must also ensure that the file MCLINK.EXT (in the same Mac folder as the MCLINK program) contains the extension ".RTF". This ensures MCLINK treats RTF file as text files, and will perform the conversion between character sets.
Note the conversion table (in file MCLINK.XLT) supplied with my Serial Link did not have entries to convert the Series 3 bullet characters (codes 250 and 254) to the equivalent Mac character (code 165). It would be worth checking this in your table.
4.2 Importing from Mac to Series 3
On the Mac save the file in RTF format. Connect the Series 3 to the Mac using the Serial Link, and establish the connection in the usual way.
Activate the MACRTF application, by moving the highlight on System screen beneath its icon and pressing Enter. A dialog will now be displayed for you to select the RTF file to be imported from the Mac and the destination (normally \WRD on one of the Series 3's drives). The application remembers the Mac disk and folder you imported the previous file from, and sets this as the default path for the file selector.
If you complete the dialog with Enter the Application carries out the following actions:
ú Copies the file unchanged from the Mac to the specified destination directory;
ú Creates a mapping file (in the destination directory, with same name as the RTF file but extension ".STY") containing font mappings from RTFMAP.DEF and style mappings generated as described above;
ú Copies this mapping file to M:\WDR\RTFMAP.TXT, ready for Word to use when translating the RTF file.
You should now open the RTF file from Word on the Series 3. You should then find all the fonts have been set correctly and styles have been given 'sensible' short codes.
Note that if you do not open the file immediately, and in the meantime perform further operations using either MACRTF or RTFMAC, then the mapping file set up as M:\WDR\RTFMAP.TXT will no longer be the correct one. If this is the case then you should manually copy filename.STY to M:\WDR\RTFMAP.TXT.
4.3 Exporting from Series 3 to Macintosh
Note the RTFMAC program runs in two stages. The first stage sets up the correct mapping file for Word's RTF translator to use. The second transfers the file to the Mac. Between these two stages the document is saved from Word as an RTF file.
The RTFMAC program lists all Word documents beneath its icon; you should highlight the document you wish to export and type Enter to start the program.
A dialog is then displayed for you to select the document to be exported and the corresponding style mapping file. For the latter you can choose:
ú a file with a specified name;
ú the default file (containing your font mappings only);
ú or no mapping file at all.
If the program finds a mapping file to match the selected Word document (i.e. same name and ".STY" extension) then it offers this. Otherwise it sets the "Use Style Map" to "Default". You can use the (lower) file selector to choose another mapping file; this would normally be the mapping file generated when the original document from which the current document has been derived was imported from the Mac. (The upper file selector specifies the Word document which is being exported.)
After you complete this dialog with Enter the program copies the specified mapping file to M:\WDR\RTFMAP.TXT, unless you selected no mapping file, in which case any existing M:\WDR\RTFMAP.TXT is deleted. The second dialog is now displayed, for you to select the destination.
However DO NOT complete this dialog, but switch to Word with the document to be exported open. From Word save it in RTF format, preferably with the same name (but extension ".RTF") and in the same directory as the original document.
Now switch back to RTFMAC and complete the dialog, by selecting the destination disk and folder on the Mac with the lower file selector. The program 'remembers' the destination path you used the previous time. The upper selector specifies the file to be transferred, initialised to the same name as the previously selected Word document with ".RTF" extension.
When you press Enter the program copies the RTF file to the specified destination on the Mac, changing the representation of non-ASCII characters as described previously. The file can then be opened from Word on the Mac.
As a bonus RTFMAC can be made to insert the current date into the document. It can do this in three different formats, corresponding to the three formats used by the Microsoft Word Glossary command. Use the following place holders in your document to specify the location and format:
®date¯ "Full" format, e.g.: Monday, April 11, 1994;
®adate¯ "Abbreviated" format, e.g.: Mon, Apr 11, 1994;
®sdate¯ "Short" format, e.g.: 11/4/94.
5 Use and Distribution
I am making this software available as freeware, and therefore it may be used free of charge. It may be freely distributed so long as no charge is made (other than to cover reasonable costs of distribution), and these notes are distributed with the programs.
While I have taken reasonable care in the production of this software, I cannot be held responsible for any loss or damage resulting from its use. If any problems are encountered I will try and assist. I can be contacted at:
John Dawson
19, St Edward's Rd.
Reading
Berkshire
England
RG6 1NL
+44 734 666185
Please 'phone outside UK office hours!
6 PC Users
I developed these programs to get round specific problems encountered while transferring to and from the Apple Macintosh. However some of the solutions adopted may also have application when transferring between the Series 3 and the IBM PC. I would be happy to talk to anyone interested in producing a PC version; please contact me as above!
